第 8 章 系统定时器接口设计说明
================================

系统定时器接口为应用层提供定时 api 接口，本章节为用户提供技术参考。

1、功能概述
############

定时器类型
<<<<<<<<<<<

1）强节拍
 | 接口：usr_timer；
 | 优先级：1 ； 
 | 异步；

 | 1、usr_timer 的参数 priority（优先级）为 1，使用该类定时器，系统无法进入低功耗。
 | 2、usr_timer 属于异步接口， add 的时候注册的扫描函数将在硬件定时器中时基到时候被调用。


2）弱节拍
 | 接口：usr_timer；
 | 优先级：0 ； 
 | 异步；

 | 1、usr_timer 的参数 priority（优先级）为 0，使用该类定时器，系统低功耗会忽略该节拍，节拍不会丢失，但是周期会变。
 | 2、usr_timer 属于异步接口，add 的时候注册的回调函数将在硬件定时器中时基到时候被调用。

3）Normal节拍
 | 接口：sys_timer；
 | 优先级：无 ； 
 | 同步；

 | 1、系统会进入低功耗，节拍不会丢失。
 | 2、sys_timer 由 systimer 线程提供时基，属于同步接口，也就是说在哪个线程 add 的 sys_timer，定时时基到了 systimer 线程会发事件通知对应的 add 线程响应（回调函数被执行）。
 | 3、需要对应 timer add 的线程响应问题， 不建议在系统主循环线程做定时时间极短的扫描。

timer 与 timerout 区别
<<<<<<<<<<<<<<<<<<<<<<<<

sys_timer/usr_timer 与 sys_timerout/usr_timerout 接口区别在于 timeout 接口的回调只会被做一次，也就是设定一个未来的时间， 时间到了响应之后便结束这个定时器的生命周期。

2、详细接口说明
##################

sys_timer 详细接口说明
<<<<<<<<<<<<<<<<<<<<<<<

.. code-block:: c

  //*----------------------------------------------------------------------------*/
  /**@brief	sys_timer 定时扫描增加接口。
  @param
  priv:私有参数。
  func:定时扫描回调函数。
  msec:定时时间， 单位：毫秒。
  @return	定时器分配的 id 号。
  @note	
  1、系统会进入低功耗，节拍不会丢失。
  2、sys_timer 由 systimer 线程提供时基，属于同步接口，也就是说在哪个线程 add 的 sys_timer，定时时基到了。
  systimer 线程会发事件通知对应的 add 线程响应（回调函数被执行）。
  3、与 sys_timer_del 成对使用。
  */
  /*----------------------------------------------------------------------------*/

  u16 sys_timer_add(void *priv, void (*func)(void *priv), u32 msec);

  //*----------------------------------------------------------------------------*/
  /**@brief	sys_timer 定时扫描删除接口。
  @param
  id:sys_timer_add 分配的 id 号。
  @return。
  @note	
  1、与 sys_timer_add 成对使用。
  */
  /*----------------------------------------------------------------------------*/

usr_timer 详细接口说明
<<<<<<<<<<<<<<<<<<<<<<<

 | 1）usr_timer 在  ``include_lib/system/timer.h``  中声明。
 | 2）sys_hi_timer 等同为 priority 为 1 的 usr_timer， 在  ``include_lib/system/timer.h``  被宏定义。
 | 3）sys_s_hi_timer 等同为 priority 为 0 的 usr_timer，在  ``include_lib/system/timer.h``  被宏定义。

.. code-block:: c

  //*----------------------------------------------------------------------------*/
  /**@brief	usr_timer 定时扫描增加接口。
  @param
  priv:私有参数。
  func:定时扫描回调函数
  msec:定时时间， 单位：毫秒。
  priority:优先级,范围：0/1。
  @return	定时器分配的 id 号。
  @note	
  1、usr_timer 的参数 priority（优先级）为 1，使用该类定时器，系统无法进入低功耗。
  2、usr_timer 的参数 priority（优先级）为 0，使用该类定时器，系统低功耗会忽略该节拍， 节拍不会丢失，但是周期会变。
  3、usr_timer 属于异步接口， add 的时候注册的扫描函数将在硬件定时器中时基到时候被调用。
  4、对应释放接口 usr_timer_del。
  */
  /*----------------------------------------------------------------------------*/

  u16 usr_timer_add(void *priv, void (*func)(void *priv), u32 msec, u8 priority);

  //*----------------------------------------------------------------------------*/
  /**@brief	usr_timer 超时增加接口。
  @param
  priv:私有参数。
  func:超时回调函数。
  msec:定时时间， 单位：毫秒。
  priority:优先级,范围：0/1。
  @return	定时器分配的 id 号。
  @note	
  1、usr_timerout 的参数 priority（优先级）为 1，使用该类定时器，系统无法进入低功耗。
  2、usr_timerout 的参数 priority（优先级）为 0，使用该类定时器，系统低功耗会忽略该节拍， 节拍不会丢失，但是周期会变。
  3、usr_timerout 属于异步接口， add 的时候注册的扫描函数将在硬件定时器中时基到时候被调用。
  4、对应释放接口 usr_timerout_del。
  5、timeout 回调只会被执行一次。
  */
  /*----------------------------------------------------------------------------*/

  u16 usr_timeout_add(void *priv, void (*func)(void *priv), u32 msec, u8 priority);